home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 526-550 / disk_539 / simplerexx / simplerexx.doc < prev    next >
Text File  |  1992-05-06  |  7KB  |  158 lines
  1.                                 SimpleRexx
  2.                                     by
  3.                                Michael Sinz
  4.  
  5.               A Simplified Interface into the world of ARexx
  6.  
  7.  
  8.      ARexx,  ARexx,  ARexx.    2.0  has  ARexx.   So, why and how do I
  9.      support ARexx?
  10.  
  11.      The "Why?" has been answered elsewhere and that is not  what this
  12.      article is  about.   Let it suffice that you should support ARexx
  13.      within your application.  It  is  a  standard  that  Commodore is
  14.      pushing and  we hope  that all  new applications  will have ARexx
  15.      support.
  16.  
  17.      As to the "How?",  that  is  what  this  article  is  about.   We
  18.      understand that  your existing software may not currently support
  19.      ARexx and that some of you may never even have looked at  what is
  20.      needed to  support ARexx.   New applications can be designed with
  21.      ARexx support in mind  and, with  the advent  of the  AppShell by
  22.      David Junod,  the work  involved to support ARexx is nothing more
  23.      than  what  is  needed  to  support   the  features   within  you
  24.      application.    However,  existing  code  may  not  move into the
  25.      AppShell to  easily and  you may  wish to  do a  minor upgrade to
  26.      your application to support ARexx.
  27.  
  28.      SimpleRexx is  a set  of routines that handle the low-level ARexx
  29.      work for you in such a way as to have your application  work with
  30.      or without ARexx on the target system.  The goal of SimpleRexx is
  31.      to make adding at least the minimum level of ARexx  support to an
  32.      application a trivial task.
  33.  
  34.  
  35.                             Working with ARexx
  36.  
  37.      REXX  is,  at  its  heart,  a  string  processing language.  Most
  38.      everything that happens in REXX is in the form of  a string; even
  39.      numbers are passed as ASCII representations in most situations.
  40.  
  41.      The Amiga  implementation of REXX, known as ARexx, and is part of
  42.      Release  2.0  of  AmigaDOS.      ARexx   has   a   very  complete
  43.      implementation of  the REXX language plus the ability to send and
  44.      receive control messages from "outside" sources.   ARexx  the can
  45.      operate  on  them  in  synchronous fashion.  The messages contain
  46.      text strings that are then interpreted by ARexx  as REXX commands
  47.      or by the "outside" source (the Application) as its commands.
  48.  
  49.      An application  that "supports ARexx" is one that can receive and
  50.      send ARexx messages.  The messages  are, like  the REXX language,
  51.      string  based  and  contain  the  command string of the operation
  52.      wanted.
  53.  
  54.      To make this even more interesting,  there are  ways to  send and
  55.      receive data from ARexx.  The data can come in the message itself
  56.      or via the ARexx RVI (Rexx Variable Interface).   In  either case
  57.      data  can  be  transferred  to  and from ARexx.  A complete ARexx
  58.      supporting application would need to be  able to  send data  to a
  59.      requesting ARexx program/script and get data from that program.
  60.  
  61.      The following  code shows how to use the ARexx support library to
  62.      send and receive ARexx messages.  It also  is a  "wrapper" around
  63.      these  functions  to  provide  a simplified interface to ARexx to
  64.      help promote  and simplify  the idea  of adding  ARexx support to
  65.      your existing applications.
  66.  
  67.      SimpleRexxExample.c is  a very  simple example  of the use of the
  68.      calls in SimpleRexx.  The test.rexx  script is  an example script
  69.      to try  running while SimpleRexxExample is running.  It will send
  70.      commands  to   SimpleRexxExample   in   order   to   control  it.
  71.      test.results is the output of test.rexx.
  72.  
  73.  
  74.                            Overview of Functions
  75.  
  76.      The source  to SimpleRexx  is a single file.  It is SimpleRexx.c.
  77.      The  header  file  to  that  contains  the  type  definitions and
  78.      prototypes for the functions is in the file SimpleRexx.h.
  79.  
  80.      Functions  that  are  "available"  via  SimpleRexx  are  used  as
  81.      follows:
  82.  
  83.  
  84.           rexx_handle=InitARexx(AppBaseName,Extension)
  85.  
  86.                This initializes a SimpleRexx context.  The rexx_handle
  87.                is much  like a  file handle in that it will be used in
  88.                all  other  calls  that  make  use  of  this SimpleRexx
  89.                context.    Since  all SimpleRexx calls correctly check
  90.                the rexx_handle before doing work, you  do not  need to
  91.                check the  return result of this call.  If ARexx is not
  92.                available on your system,  SimpleRexx will  just not do
  93.                anything.
  94.  
  95.  
  96.           port_name=ARexxName(rexx_handle)
  97.  
  98.                This  function  returns  a  pointer  to the name of the
  99.                ARexx port for your context.  The name is based  on the
  100.                AppBaseName  plus   an  invocation   number  such  that
  101.                multiple copies of an application can  run at  the same
  102.                time.  If you have no ARexx port, it returns NULL.
  103.  
  104.  
  105.           sigmask=ARexxSignal(rexx_handle)
  106.  
  107.                This  function  returns  the  signal  bit  mask that is
  108.                needed for the port that is part of your context.  This
  109.                should be  combined with  other signal masks to produce
  110.                the argument to the Wait() call.  This  returns NULL if
  111.                there is no signal mask.
  112.  
  113.  
  114.           rmsg=GetARexxMsg(rexx_handle)
  115.  
  116.                This  function  returns  the  next Rexx message that is
  117.                waiting.  rmsg==NULL if there is no message or ARexx is
  118.                not around.   rmsg==REXX_RETURN_ERROR if a message sent
  119.                to ARexx via SendARexxMsg() returns an error.
  120.  
  121.  
  122.           ReplyARexxMsg(rexx_handle,rmsg,result,error)
  123.  
  124.                This function  replies  the  ARexx  message  gotten via
  125.                GetARexxMsg().   The "result"  is a pointer to a result
  126.                string that is  returned  via  OPTIONS  RESULTS  in the
  127.                RESULT ARexx variable.  If you have no result, set this
  128.                to NULL.  Error is the error severity  level.   If this
  129.                is 0,  the result  string will  be returned, if this is
  130.                non-zero, the error level will be returned in RC.
  131.  
  132.  
  133.           worked=SendARexxMsg(rexx_handle,string,StringFileFlag)
  134.  
  135.                This function sends the string to  ARexx.   It sets the
  136.                default host  to the  context and  sets the RXFB_STRING
  137.                bit in the  message  if  the  "StringFileFlag"  is set.
  138.                This routine  returns FALSE if the message was not sent
  139.                for some reason.
  140.  
  141.  
  142.           worked=SetARexxLastError(rexx_handle,rmsg,ErrorString)
  143.  
  144.                This function uses the RVI (Rexx Variable Interface) to
  145.                set  a  variable  named  <AppBaseName>.LASTERROR to the
  146.                ErrorString.  This is where the  "error" message should
  147.                go if  there is  an error.  This function returns FALSE
  148.                if this fails for any reason.
  149.  
  150.  
  151.           FreeARexx(rexx_handle)
  152.  
  153.                This closes a SimpleRexx  context.   The rexx_handle is
  154.                one that  was gotten  from InitARexx().  The routine is
  155.                fully error checked so that you can pass it a  NULL and
  156.                it  will  do  nothing.    This is useful if you want to
  157.                just blindly use the rexx_handle.
  158.